feat(context): add context_manager="auto" facade on Agent by lizradway · Pull Request #2643 · strands-agents/harness-sdk

lizradway · 2026-06-05T19:27:11Z

Description

Adds contextManager: "auto" / context_manager="auto" as an opt-in parameter on Agent in both SDKs. When set, it wires up the benchmark-winning context management configuration:

ContextOffloader(storage=InMemoryStorage(), maxResultTokens=1500, previewTokens=750) — caches oversized tool results, keeps truncated previews in context, provides retrieve_offloaded_content tool
SummarizingConversationManager(summaryRatio=0.3, compressionThreshold=0.85) — summarizes older messages on context overflow, proactively compresses at 85% context window usage

Coexistence rules:

If user also provides conversationManager, theirs is used (offloader still added)
If user already has a ContextOffloader in their plugins list, it's not overridden
Throws with stateful models (they manage context server-side)

from strands import Agent

agent = Agent(model="us.anthropic.claude-sonnet-4-6-v1", context_manager="auto")

import { Agent } from '@strands-agents/sdk'

const agent = new Agent({ model: 'us.anthropic.claude-sonnet-4-6-v1', contextManager: 'auto' })

Related Issues

strands-agents/docs#831

Documentation PR

N/A — docs PR (strands-agents/docs#831) covers the design. User-facing docs page to follow once this ships.

Type of Change

New feature

Testing

Python: 16 unit tests covering all resolution paths, 502 existing agent tests pass
TypeScript: 10 unit tests covering all resolution paths, 122 existing agent tests pass
hatch fmt --linter --check passes (ruff + mypy)
tsc --noEmit passes
Merged with latest upstream/main, conflicts resolved, all tests re-verified
I ran hatch run prepare

Checklist

I have read the CONTRIBUTING document
I have added any necessary tests that prove my fix is effective or my feature works
I have updated the documentation accordingly
I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
My changes generate no new warnings
Any dependent changes have been merged and published

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

One-liner that composes ContextOffloader + SummarizingConversationManager with benchmark-validated defaults (1500/750 token thresholds, 0.3 summary ratio). Saves 54% tokens on Sonnet, improves code retrieval by 20% on complex tasks with Opus.

Adds proactive compression (compression_threshold=0.85) to the default SummarizingConversationManager created by context_manager="auto". This triggers context reduction before hitting the window limit.

github-actions · 2026-06-05T19:53:43Z

Assessment: Comment

Clean, well-scoped feature that aligns with the SDK tenets (simple at any scale, extensible by design). The coexistence rules are well thought out.

Review Themes

Validation ordering: The stateful model check fires after objects are already constructed, and the error message doesn't reflect the new context_manager trigger.
Runtime safety: No runtime guard against invalid context_manager values (only type-checked); per tenet 4, a helpful ValueError would be appropriate.
Documentation completeness: The proactive_compression threshold (0.85) is a meaningful behavioral default that should be surfaced in the docstring and the _resolve_context_manager method should have a full Google-style docstring.
Test reliance on private internals: Most assertions reach into _-prefixed attributes; this is pragmatic given the current API surface but worth acknowledging for future maintenance.
API review process: This introduces a new public parameter on Agent — per API_BAR_RAISING.md, consider adding the needs-api-review label.

Nice feature that makes context management accessible in a single parameter — well aligned with "simple things should be simple."

- Move stateful model validation before resolution (avoid unnecessary allocation) - Update error message to mention both context_manager and conversation_manager - Add runtime ValueError for unsupported context_manager values - Add compression_threshold=0.85 to docstring - Expand _resolve_context_manager docstring with full Args/Returns/Raises - Fix MyPlugin test to inherit from Plugin ABC - Add test for unsupported value error

github-actions · 2026-06-05T20:08:51Z

Assessment: Approve

All previous feedback has been addressed — the code now validates before constructing, has accurate error messages, includes runtime guards for unsupported values, and has complete documentation.

Changes verified

✅ Stateful model validation occurs before _resolve_context_manager
✅ Error message mentions both context_manager and conversation_manager
✅ Runtime ValueError for unsupported context_manager values with test coverage
✅ Docstring includes compression_threshold=0.85
✅ _resolve_context_manager has full Google-style docstring with Raises section
✅ MyPlugin in tests properly inherits from Plugin ABC

One remaining consideration: this introduces a new public API parameter on Agent. Per API_BAR_RAISING.md, the needs-api-review label may still be appropriate depending on team norms for moderate-scope changes.

Same facade as the Python SDK — one-liner that composes ContextOffloader (maxResultTokens=1500, previewTokens=750) with SummarizingConversationManager (summaryRatio=0.3, compressionThreshold=0.85) using benchmark-validated defaults.

github-actions · 2026-06-08T15:37:44Z

Assessment: Approve

Clean, opt-in facade that composes benchmark-validated context management primitives behind a single parameter. Pay-for-play design (existing agents unaffected), proper validation ordering, and comprehensive cross-SDK test coverage.

Remaining Items

Missing TS export (inline comment on src/index.ts:16): ContextManagerStrategy should be re-exported for parity with ToolExecutorStrategy
Durability caveat (inline comment on agent.py:219): Docstring should note that InMemoryStorage doesn't persist across restarts — users pairing with session_manager need explicit ContextOffloader with durable storage
API process: Consider needs-api-review label per API_BAR_RAISING.md for this new public Agent parameter (moderate scope)

Well-aligned with "simple things should be simple" and "provide both low-level and high-level APIs" tenets.

github-actions · 2026-06-08T15:55:19Z

Assessment: Approve

Well-designed opt-in facade that composes benchmark-validated context management primitives (ContextOffloader + SummarizingConversationManager) behind a single context_manager="auto" parameter. Pay-for-play design, proper validation, and comprehensive cross-SDK test coverage.

Review Details

API design: Aligns with "simple things should be simple" and "extensible by design" tenets — the facade composes primitives without hiding them, and the coexistence rules are well thought out
Missing export (1 inline comment): ContextManagerStrategy type should be re-exported from src/index.ts per "Prefer Flat Namespaces" decision
Documentation gap (1 inline comment): Docstring should warn about InMemoryStorage non-durability when paired with session_manager per tenet 4
API process: This adds a new public parameter on Agent (moderate scope per API_BAR_RAISING.md). Consider adding the needs-api-review label if not already tracked via the linked docs issue

The get_args(ContextManagerStrategy) pattern for runtime validation derived from the type definition is a nice touch for keeping type and validation in sync.

github-actions · 2026-06-08T16:06:28Z

Assessment: Approve

Clean opt-in facade that composes ContextOffloader + SummarizingConversationManager behind a single context_manager="auto" parameter. The design aligns with "Provide Both Low-Level and High-Level APIs" and "Pay for Play" decisions — existing agents are unaffected, and users can always drop to explicit primitives for fine-grained control.

Review Details

Missing exports (2 inline comments): ContextManagerStrategy should be re-exported from both strands-ts/src/index.ts and strands-py/src/strands/agent/__init__.py per "Prefer Flat Namespaces" decision. Users who type-annotate wrapper functions need access without reaching into internal module paths.
Durability caveat (1 inline comment): The TS docstring has the same gap flagged in the open Python thread — InMemoryStorage + sessionManager creates dangling offload references on session restore. Both SDKs should document this.
Prior feedback: All 12 resolved threads have been addressed cleanly — validation ordering, runtime guards, constants extraction, plugin ordering parity, and full docstrings are all solid.

The implementation is well-structured, test coverage is comprehensive across both SDKs, and the coexistence semantics (user CM precedence, offloader dedup, stateful model guard) are correct and consistent.

- TS: CM_* → CONTEXT_MANAGER_* constants - Tests: user_cm → user_conversation_manager, cm → conversationManager

github-actions · 2026-06-08T16:44:20Z

Assessment: Approve

Well-designed opt-in facade — all prior feedback addressed, cross-SDK consistency is solid, durability caveat now documented in both SDKs.

One remaining item

Missing export: ContextManagerStrategy should be re-exported from src/index.ts (TS) and strands/agent/__init__.py (Python) per "Prefer Flat Namespaces" decision. ToolExecutorStrategy is already exported at those levels — this should be consistent.

lizradway added 2 commits June 5, 2026 15:06

feat(strands-py): enable proactive compression at 0.85 threshold

f011cec

Adds proactive compression (compression_threshold=0.85) to the default SummarizingConversationManager created by context_manager="auto". This triggers context reduction before hitting the window limit.

github-actions Bot added the size/m label Jun 5, 2026

lizradway requested a deployment to manual-approval June 5, 2026 19:27 — with GitHub Actions Waiting

style: fix import sorting in _resolve_context_manager

dfe1652

github-actions Bot added size/m and removed size/m labels Jun 5, 2026

lizradway temporarily deployed to manual-approval June 5, 2026 19:43 — with GitHub Actions Inactive

lizradway requested a deployment to manual-approval June 5, 2026 19:43 — with GitHub Actions Waiting

github-actions Bot added the strands-running label Jun 5, 2026